Readme.txt - HarnessMX.cfm 1.06 by Jeff Peters (jeff@grokfusebox.com)
05 Jul 2005
====================================================================
HarnessMX is a tool that constructs test harnesses for ColdFusion applications developed using the Fusebox methodology.  It operates on the assumption that files incorporate documentation headers using the Fusedoc 2.0 standard developed by Hal Helms.
-------------------
For information on Fusebox, visit http://www.fusebox.org
For information on Fusedoc, visit http://www.halhelms.com
-------------------
HarnessMX is based on the original Harness concept by Jeff Peters.  Additional work done by 
Kevin Roche (kevin@objectiveinternet.com)
Marnen Laibow-Koser (marnen@marnen.org)

When in the production environment, fusebox files perform their work and return control to the fusebox file.  Test harnesses are a way to provide the variables expected by a fuse and observe the output of the fuse as a unit.  This allows you to unit test your code before placing it into a full test environment, making final debugging much less painful.

In order to facilitate unit testing, we make use of a variable called "self" to tell the fuse the location to call next.  In production, of course, this variable contains the value "index.cfm", the fusebox file.  Test harnesses assign a different value to the variable, allowing the use of another process to dump variables, or whatever you wish to use in monitoring output from the fuse being unit tested.

=================
Prerequisites
=================
HarnessMX should run without problems in any version of ColdFusionMX from 6 on.

=================
Using HarnessMX
=================
What does HarnessMX do?  It recurses the directory tree, starting in the specified directory, and creates a test harness for any file with a Fusebox prefix of "dsp" or "act".  If the file has a Fusedoc header in it, HarnessMX will read the Fusedoc and do its best to create the required variables in the file's test harness.  If the file doesn't have a properly constructed Fusedoc header, HarnessMX will throw an error and inform you of the name of the file where the offending Fusedoc lives.  (Mind those closing slashes!)

Before you run HarnessMX, take a look at the harnessMX.ini file.  This configuration file tells HarnessMX how you'd like the global initialization lines in your test harnesses to look.  You may modify the lines as you wish; the LineCount key tells HarnessMX how many lines to use.  For example, if you design keys for Line1 through Line17, but you set LineCount equal to 5, HarnessMX will only use lines 1 through 5.

Once you have a harnessMX.ini that meets with your approval, you're ready to run HarnessMX.  It's called as a custom tag; you can place HarnessMX.cfm and harnessMX.ini in your Custom Tags directory or in the directory at the top of the application for which you're building harnesses.  You can also create any number of ini files and tell HarnessMX which one to use with the "ini" attribute.

The template "har2Call.cfm" shows a sample use of HarnessMX.  The attributes available are:

 thisDir: directory from which to start process.  
          Defaults to current directory.
          
 verbose: whether to display process information.  
          Defaults to Yes.
          
prefixes: a list of file prefixes to process.  
          Defaults to "dsp,act"
          You may use "*" to cause HarnessMX to ignore file prefixes and create a test harness 
          for all files found.  Be careful if you use the * value--be sure you really want 
          HarnessMX to process ALL the files in the directory structure.
          
     ini: file containing global harness settings.  
          Defaults to "harnessMX.ini" in the directory where HarnessMX.cfm is 
          located (usually your CustomTags directory).

Once you've run HarnessMX, you'll have a test harness for each file that passes the prefixes filter.  Test harnesses add a prefix of "tst_" to the file name.

Note that HarnessMX, because of its much more thorough nature compared with the original Harness, may take a bit of time to process through a complete application.  Patience is the watchword--after all, you could be coding all those test harnesses by hand, right?  Have a cup o'joe and watch the show.

Happy Testing!
- Jeff Peters

=================
Version History
=================
1.06 - 2005-07-05: Fixed bug that caused all simple data types to duplicate first cfset line of that type in the <in> section.
1.05 - 2005-04-30:
- Contributions by Marnen Laibow-Koser (marnen@marnen.org)
- Now uses CFMX's built-in XML parser
1.04 - 2003-01-31:
- Contributions by Kevin Roche (kevin@objectiveinternet.com)
- Limits processing to start mode.
- Adds comments to test harnesses.
- Adds include section from HarnessMX.ini at the end of the harness file (ShowResults section of HarnessMX.ini)
- Adds UserData section to HarnessMX.ini.
1.03 - 2003-01-17: Update prevents styles from being written more than once. 
1.02 - 2003-01-10: First public release that makes the author happy. ;)  This code is functional, though quite bloated.  Streamlining may (or may not) follow as time permits.
1.01 - 2002-08-02: First public release; pulled due to fatal bug in processing nested complex Fusedocs.
1.00 - 2001-10-23: Initial version; not released to public.
